Inside Macintosh: Programming With JManager /

Chapter 1 - Using JManager

Creating a Java Runtime Session

If you want to run Java applets on the Mac OS platform, your embedding application must first create a Java runtime session. This session can then load and execute Java code.

Beginning a Java Runtime Session

On the Mac OS platform, the Java runtime session is defined by the JMSessionRef object. To instantiate this object, you must call the function JMOpenSession. Listing 1-1 gives an example of creating a session.

Listing 1-1 Creating a session

static JMSessionRef theSession;

static Boolean initializeMRJ()
{
      
   JMSessionCallbacks sessionCallbacks = {
      kJMVersion,    /* the current version */
      MyStandardOutput, /* designated standard output */
      MyStandardError,/* designated standard error */
      MyStandardIn   /* designated standard input */
      MyExit         /* System.exit handler */
      MyAuthenticate /* URL Authentication handler */
      MyLowMem       /* Low memory condition handler */
   };
   
   return JMOpenSession(&theSession, eJManager2Defaults,
                  eCheckRemoteCode, &sessionCallbacks,
                  kTextEncodingMacRoman, 0) == noErr;
}

The instantiated JMSessionRef object is referenced by the value of theSession. Other JManager functions require you to pass this value to identify the session. (You can create more than one instantiation of the Java runtime environment if you wish.) Note that the JMSessionCallbacks structure you pass contains a field indicating the version of JManager you are using in your program. You should always set this value to kJMVersion. Setting this value prevents your program from accessing older (possibly incompatible) JManager functions.

The text encoding you specify when calling JMOpenSession (kTextEncodingMacRoman in this example) indicates the encoding used for any data sent to the designated standard output or standard error.

Session and Security Options

When calling JMOpenSession, you pass two parameters that indicate the desired session options, and whether you want to use the code verifier.

• The session options parameter is actually a mask that allows you to select various options, such as the following:
  • Whether the Java session can use temporary memory in addition to application heap memory. The default uses application heap memory only.
  • Whether to use the Just In Time (JIT) compiler. The default enables the compiler.
  • Whether to allow debugging. The default disables the debugger.
  • Whether to use preferences determined by InternetConfig. The default uses InternetConfig settings.
  • Whether to inhibit class unloading (that is, to prevent garbage collection of classes that are not being used). The default allows class unloading.

    The example in Listing 1-1 passes eJManager2Defaults, which selects all the default settings. See "Runtime Session Options" for a list of the available options.

• The code verifier parameter (set to eCheckRemoteCode in Listing 1-1) specifies whether you want the code verifier to check the Java code before attempting to execute it. The code verifier analyzes the code to make sure that it is valid Java code and that it does not attempt any illegal or questionable actions (such as pointer arithmetic) that could give the code access to the Mac OS runtime environment. Typically you should use the code verifier if you plan to receive Java code from an untrustworthy source (such as over a network). See "Security Level Indicators" for the available options.

  After calling JMOpenSession, you can read or modify the code verifier setting by calling the functions JMGetVerifyMode or JMSetVerifyMode respectively.

Callbacks

The data structure you must pass to the JMOpenSession function is a set of callback functions to handle console input and output, calls to exit from a Java application, low memory conditions, and URL authentication.

• The standard output, standard error, and standard input callbacks all deal with communications with the command line console. For example, you could specify a function that would receive and parse text sent to the standard output. Since the Mac OS runtime environment does not have a command line, these callbacks are often unused and set to nil. (By default, any text sent to standard output or standard error is redirected to a file.) For information about the form of these functions, see MyStandardOutput, MyStandardError, and MyStandardIn.
• The exit handler handles the case where the Java application quits (by calling java.lang.System.exit). Your callback can dispose of the applet or session as it sees fit, or it can simply allow the System.exit call to execute normally. For more information about the form of the exit handler, see MyExit.
• The URL authentication handler is called in cases where the user must enter a name and password to gain access to a URL. The handler should prompt the user for the proper information and pass it back to the Java program, which then decides whether the information is valid. For more information about the form of the authentication handler, see MyAuthenticate.
• The low memory handler is called when the Java runtime session runs low on memory. For more information about the form of the low memory handler, see MyLowMem.

For more information about the session callback structure, see "Session Callbacks Structure".

Specifying Proxy Servers

If you want to define proxy servers for a session, you can do so using the JMSetProxyInfo function. A proxy server essentially acts as a gateway when you access data over a network. For example, if your company has a security firewall, all requests for code or data external to the company network must pass through the firewall before reaching the desired server. You can designate proxy servers for HTTP access, FTP access, and firewall access.

Note

If you allowed the use of the InternetConfig settings when creating the session, any proxy information defined there is used for the default settings.

You pass a proxy server options structure to the JMSetProxyInfo function for each type of server. For example, Listing 1-2 sets a firewall proxy server.

Listing 1-2 Specifying a firewall proxy server

JMProxyInfo myFirewallProxyInfo {
   true,       /* allow a proxy for this type of server access */
   "TheWall.myCompany.com",/* the name of the server */
   80};        /* the port number of the server */

JMSetProxyInfo(theSession, eFirewallProxy, &myFirewallProxyInfo);

The myFirewallProxyInfo structure specifies the firewall server by name and by port number. (If you wanted to specify HTTP or FTP proxy servers, you would create a structure for each of them as well.) You then set these values by calling the JMSetProxyInfo function and specifying the firewall proxy.

To read proxy information for a given session, you must call the JMGetProxyInfo function. See "Proxy Server Options" and "Session Security Indicators" for more information about the values you pass to these functions.

Checking JManager Versions

Many JManager data structures require that you specify the version of JManager (kJMVersion) you are compiling against. Before beginning a session, you should compare this value to the version of JManager available on the host computer to make sure that the two are compatible. The function JMGetVersion returns the JManager version available on the host computer.

IMPORTANT

If you do not specify JManager as a weak library when compiling, your application will automatically fail to launch if the JManager library is not present. If you weak-link to the JManager library, your code should check that the JMGetVersion symbol is valid (that is, its value is not nil) before calling it.

Properties and Client-Specific Session Data

Since the session is a JMSessionRef object, you can assign or change properties associated with it. You can do this using the functions JMGetSessionProperty and JMPutSessionProperty. These functions correspond respectively to the Java methods java.lang.System.getProperty and java.lang.System.setProperty. If the property name you specify does not exist, then JManager creates a new property with that name.

You can also read or set optional client data for a given session using the functions JMGetSessionData and JMSetSessionData. For example, if you have multiple sessions running at the same time, you might want to store specific data with each one.

Servicing Other Threads

When you are running a Macintosh embedding application, you must explicitly tell JManager to give up time to the Java virtual machine. You do so by using the JMIdle function in your main event loop. Listing 1-3 shows an example of using JMIdle.

Listing 1-3 Using the JMIdle function

Boolean MainEventLoopContinues = true; 

while (MainEventLoopContinues) {
   EventRecord eve;
   
   if (! WaitNextEvent(everyEvent, &eve, 30, nil) || 
      eve.what == nullEvent)
         JMIdle(theSession, 100);
      else
         handleEvent(&eve);
   }

The value specified in JMIdle indicates how many milliseconds to allot to other threads; you can specify a default wait period by using the value kDefaultJMTime. JMIdle returns immediately if no threads need servicing. JMIdle also returns if a user event occurs in the current session.

Ending a Java Runtime Session

After you have finished executing your Java programs, you should end the Java runtime session by calling the function JMCloseSession. This function disposes of the JMSessionRef object and removes any resources that JManager may have allocated for it. However, if you created any resources (such as AWT contexts and applets) within the session, you should explicitly remove them before calling JMCloseSession.

---

Subtopics

Beginning a Java Runtime Session

Session and Security Options

Callbacks

Specifying Proxy Servers

Checking JManager Versions

Properties and Client-Specific Session Data

Servicing Other Threads

Ending a Java Runtime Session